home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 5 / Apprentice-Release5.iso / Source Code / Libraries / Sherlock 2.0 / Mac v2.0 docs / Text Docs / Mac SPP Reference .txt < prev    next >
Text File  |  1996-04-05  |  6KB  |  310 lines
  1. Macintosh SPP Reference
  2.  
  3.  
  4.  
  5. SPP copies an input file to an output file, inserting Sherlock macros as it does so.  Several options 
  6. vary the kind of macros output that SPP inserts.  These options are discussed in detail below.
  7.  
  8.  
  9. SPP handles all styles of C syntax, from K&R to ANSI C Standard.  SPP will place correct 
  10. macros in the appropriate locations in spite of most syntax errors.  However, I recommend that  
  11. you use SPP only on syntactically correct files.
  12.  
  13.  
  14. The Macintosh version of SPP gets its arguments from a file call SPP_args, which must be in the 
  15. same folder as the SDIF application.  See the supplied copy of SPP_args for an example.
  16.  
  17.  
  18. SPP will insert no macros in any function containing an FTAG, FTAGV, SL_NAME, or 
  19. SL_DISABLE macro.  The SL_ENABLE macros forces SPP to insert macros into a function.  
  20.  
  21.  
  22. SPP warns about functions that do not return a value and are not explicitly declared void.
  23.  
  24.  
  25. SPP issues the warning, “Macro found where entry macro should be,” if SPP finds a macro call 
  26. where the first executable statement of a function is expected.  In such cases, SPP will skip the 
  27. generation of an entry macro, i.e., TICKB or TRACEPB.  Instead, SPP assumes the macro starts 
  28. executable code.
  29.  
  30.  
  31. Usage
  32.  
  33.  
  34.     spp2 [options] in out
  35.  
  36.  
  37. Options preceding the name of an input_file apply to that file and to all succeeding files unless 
  38. over-written by later options. 
  39.  
  40.  
  41.  
  42. Options
  43.  
  44.  
  45. +-d id=string    // define a constant
  46.  
  47.  
  48. Define id to be string, as if the statement #define id string appeared at the start of the program.  A 
  49. space must separate –d and id, but no space may appear in string or around the equal sign.  The 
  50. string is optional, in which case the equal sign can be omitted.  Examples:
  51.  
  52.  
  53.     -d STDC=1
  54.  
  55.     -d SHERLOCK
  56.  
  57.  
  58. +-exxx           // Use exxx routines (default)
  59.  
  60.  
  61. Cause SPP to output the exxx family of routines in tracing statements.  This option is the default 
  62. unless overridden by one of the following options: printf, sl_fmt, tick or usr.
  63.  
  64.  
  65. +-ftag        // generate FTAG macros
  66.  
  67.  
  68. Generate FTAG macros.  This option is on by default.
  69.  
  70.  
  71. +–f <file name>    // use synonym file
  72.  
  73.  
  74. Use alternate macro names instead of standard macro names.  The named file contains a list of 
  75. synonym lines.  Each line contains two macro names, a standard name and a synonym. The pound 
  76. character (#) starts a comment which continues to the end of the line.  An example synonym file:
  77.  
  78.  
  79.     #synonym file:  May 20, 1988
  80.  
  81.     TICKB        tickb
  82.  
  83.     TICKX        tickx
  84.  
  85.     SL_DUMP    dump
  86.  
  87.  
  88. +–i            // Insert #include <sl.h>
  89.  
  90.  
  91. Insert the line #include <sl.h> at the start of the output file.
  92.  
  93.  
  94.  
  95. +–n            // Allow nested comments
  96.  
  97.  
  98. Allow nested comments.  By default, comments do not nest.
  99.  
  100.  
  101. +-of <name>       // Specify output file
  102.  
  103.  
  104. Specify the name of the output file.  This option must appear on the command line before the name 
  105. of the input file.
  106.  
  107.  
  108. +-printf          // Use printf routines
  109.  
  110.  
  111. Output printf statements inside tracing macros.
  112.  
  113.  
  114. +-return          // Insert RETURN_xxx macros
  115.  
  116.  
  117. Replace return statements by RETURN_XXX macros.  This option is obsolete and is included 
  118. only for backward compatibility.  Its use is discouraged.
  119.  
  120.  
  121. +-sl_fmt          // Use sl_fmt routines
  122.  
  123.  
  124. Output sl_fmt statements inside tracing macros.  This option is obsolete and is included only for 
  125. backward compatibility.  Its use is discouraged.
  126.  
  127.  
  128. +-s <path>        // Look for include files in path
  129.  
  130.  
  131. Add <path> to the list of paths used to search for include files.  More than one –s option may be 
  132. used.  A space must separate –s and <path>.  Example:
  133.  
  134.  
  135.     -s \usr\include
  136.  
  137.     -s \sources
  138.  
  139.     -s \sherlock
  140.  
  141.  
  142. +-tick            // Insert tick-style macros
  143.  
  144.  
  145. This option suppresses entry and exit macros.  Only TICK macros are generated.
  146.  
  147.  
  148.  
  149. +-usr             // Use usr output routines
  150.  
  151.  
  152. Output sl_cout and related support routines inside tracing macros.  This option is obsolete and is 
  153. included only for backward compatibility.  Its use is discouraged.
  154.  
  155.  
  156. +-u id            // Undefine a preprocessor constant
  157.  
  158.  
  159. Undefine id, as if the statement #undef id appeared at the start of the program.  A space must 
  160. separate –u and id.
  161.  
  162.  
  163. +-v               // Verbose output
  164.  
  165.  
  166. Enable verbose output from SPP.  All such output goes to the log window.
  167.  
  168.  
  169. +-x               // Allow single-line comments
  170.  
  171.  
  172. Allow single-line comments.  This option is on by default.
  173.  
  174.  
  175. +-?               // Print the version number and exit
  176.  
  177.  
  178.  
  179.  
  180. Examples
  181.  
  182. The following examples assume that the input to SPP is as follows:
  183.  
  184.                 
  185.  
  186.     int example(char * s, double d)
  187.  
  188.     {
  189.  
  190.         int i;
  191.  
  192.         i = 25;
  193.  
  194.         return i;
  195.  
  196.     }
  197.  
  198.  
  199. The default output from SPP will be:
  200.  
  201.  
  202.     int example(char * s, double)
  203.  
  204.     {
  205.  
  206.         FTAG("example");
  207.  
  208.         int i;
  209.  
  210.         TRACEPB(ftag, es(s); ecs(); edouble(d); enl());
  211.  
  212.         i = 25;
  213.  
  214.         TRACEPX(ftag, eret(); eint(i); enl());
  215.  
  216.         return i;
  217.  
  218.     }
  219.  
  220.  
  221. With the +printf option, the output will be:
  222.  
  223.  
  224.     int example(char * s, double d)
  225.  
  226.     {
  227.  
  228.         FTAG("example");
  229.  
  230.         int i;
  231.  
  232.         TRACEPB(ftag, printf("(%s, %f)\n", s, d));
  233.  
  234.         i = 25;
  235.  
  236.         STATX(ftag);
  237.  
  238.         return i;
  239.  
  240.     }
  241.  
  242.  
  243.  
  244. With both the +printf and +return options enabled, the output will be:
  245.  
  246.  
  247.     int example(char * s, double d)
  248.  
  249.     {
  250.  
  251.         FTAG("example");
  252.  
  253.         int i;
  254.  
  255.         TRACEPB(ftag, printf("(%s, %f)\n", s, d));
  256.  
  257.         i = 25;
  258.  
  259.         RETURN_INT(ftag, i);
  260.  
  261.     }
  262.  
  263.  
  264. With the +tick options the output will be:
  265.  
  266.  
  267.     int example(char * s, double d)
  268.  
  269.     {
  270.  
  271.         FTAG("example");
  272.  
  273.         int i;
  274.  
  275.         TRACEP(ftag, es(s); ecs(); edouble(d); enl());
  276.  
  277.         i = 25;
  278.  
  279.         return i;
  280.  
  281.     }
  282.  
  283.  
  284. With the +usr option the output will be:
  285.  
  286.  
  287.     int example(char * s, double d)
  288.  
  289.     {
  290.  
  291.         FTAG("example");
  292.  
  293.         int i;
  294.  
  295.         TRACEPB(ftag,
  296.  
  297.             sl_cout('(');
  298.  
  299.             sl_sout(string);  sl_sout(", ");
  300.  
  301.             sl_dout(d);       sl_sout(")\n"));
  302.  
  303.         i = 25;
  304.  
  305.         STATX(ftag);
  306.  
  307.         return i;
  308.  
  309.     }
  310.